----------------------------------------------------------------------
Additional information to the SOFTBRENNER instructions
----------------------------------------------------------------------

CONTENTS:

- What has changed ?

- How does the ROM generator work ?

- The ROM generator options

- New options of SOFTBRENNER V1.22

- Hints 'n help
     Upgraded ROM-RAM-BOX
     'Park' ROMs
     'Real' ROMs
     Cruncher
     Problems with crunched programs
     Multipart programs
     Autostart
     Saving
     Editor
     'PLUS'-DOS-ROM-hint (for PLUS owners only)
     'RAM-ROM' selection 8-15
     Old versions  (V1.02-V1.15)
     Extract programs (XTRACT)
     Checksum
     Softbrenner ROM V1.22
     Utility ROM V1.16
     Install.asm

----------------------------------------------------------------------
The new SOFTBRENNER 1.22 - what has changed ?

- since version 1.11:
  a completely new powerful ROM generator has been implemented. Now it is
  possible to integrate several programs into one ROM. There is no limitation
  to binary files anymore - now you can also put BASIC programs in a ROM.
  Furthermore it is now possible to put files in a ROM which are longer than 
  16KB (up to about 31KB) -  the program will be split up into two ROMs !
  You can even 'autostart' your programs (BASIC & binary !!): after having
  reset the CPC the 'autostart' program will start automatically.
  
- since the ROM-RAM-BOX can now be upgraded to 16 'RAM ROMs' the SOFTBRENNER 
  handles the 'RAM ROMs' 8-15, too !

- a ROM editor for quick changes and patches has been implemented. Now you
  needn't leave the SOFTBRENNER if you only want to change a RSX name or some
  other easy peasy thing.
                                                                 
- right before installing a ROM, the checksum is changed automatically so that
  you needn't use the 'CHECKGEN' program anymore.

- the irritating fact that ROM named 'BASIC' or 'CPM ROM' have been considered
  as switched off in the 'SHOW ROMs' option has been changed.

- ROMs that don't have a 0,1,2,254 or 255 as their first byte are now
  considered as data trash and 'TRASH' will be displayed.

- RSX commands of a ROM can now be printed - quite handy with ROMs with many
  RSX commands. 

- the new SOFTBRENNER does only run on a CPC 6128 (PLUS) although no E-RAM
  is used, so 464 owners can get a 464 version on demand. The new XTRACT option
  (since  V1.18) does use ERAM block 3 (&C7).

- some options (install, kill, park) can also be done in BASIC using the 
  corresponding RSX command.

- the colour can now be changed.

- since version 1.15:
  ROMs can now be 'parked' very easily. 

- since version 1.18:
  programs which have been implemented using the ROM generator v1.11-1.22
  can now be extracted using the XTRACT option. 
 

----------------------------------------------------------------------
                       THE ROM GENERATOR V1.22
----------------------------------------------------------------------

How does the ROM generator work ?

After having started the ROM generator you can fill the currently empty
ROM with the programs you like. The programs can be loaded from disc and
you can choose an RSX command to start the program. The current ROM can
be saved or installed at any time. You can also load a ROM that was generated
using the ROM generator and change it (for example add some new programs).
You can also use the 'GET ROM' option to 'grab' a ROM and change the grabbed 
ROM which is now the current ROM.

To change a ROM includes: you can add new programs, change the ROM name, the 
versionnumber or the promptmessage (promptmessage= the text a ROM displays when
the CPC is switched on. You can also delete programs using the 'DELETE RSX'
option or you can delete the complete ROM ('ROM delete'= default settings).

You can add a maximum of 32 programs to a ROM. The number of entries is
displayed (at the beginning: 0 of 32). The percentage of free memory in
the ROM is also displayed as well as the current end address of the programs
in the ROM (at the beginning: memory free from &C2E2  FREE 100%).
If a program does no fit into the current ROM it can be split up into two
ROMs. The longest file that can be processed may be about 31KB long (if you
desperately need a program to fit into a ROM you should try to crunch it. See 
also Hints 'n help).

There is no limitation to a certain filetype: you can put binary programs
as well as BASIC programs into a ROM. If you want to make the best use
of the available memory in a ROM you should try to use 'real' ROM programs
(programs that run IN the ROM -> they don't need to be copied into the RAM. See 
also Hints 'n help).
You have the interesting possibility to 'autostart' a program after a reset
of the CPC (for example you can redefine the keys, change the colours, etc.).

----------------------------------------------------------------------
                 The ROM generator options
----------------------------------------------------------------------

The options are mainly self-explaining, so only the main options are 
explained here:

-X- ADD RSX

The most important option of the ROM generator: you have to choose a program
that should be integrated into the current ROM.

After having chosen the program you get some information about the file.
Using this information it is ofter much easier to decide how the 
program has to be implemented.

You will then be asked to enter some information. For each input the ROM
generator makes a suggestion which you can accept by pressing the ENTER key.
By choosing the suggestion you can get results even if you are in a hurry
(the given suggestions are not always the best choice, but they are only 
suggestions which you don't have to accept !).

You may enter the desired name of the RSX command which later starts the
program in the ROM. The ROM generator suggests a command name (normally the
filename of the program). It is important not to use spaces in the command
name since otherwise the command couldn't be executed by BASIC.

You will then be asked what should be done with the program after its 
RSX command has been entered. The possibilities are: 

-1- only copy into the RAM
-2- copy into the RAM and start
-3- start IN the ROM

Again the ROM generator makes a suggestion which may be accepted by pressing
the ENTER key. In case of BASIC programs you should choose between -1- and -2-.

In case that there is no entryaddress available (Entryaddres: &0000, a screen
for example) you should choose -1-.
If a program is located in the area between &C000-&FFFF it is most probable
that it is a 'real' ROM program and you should choose -3-. In this case you have
to make sure that the startaddress of the program is the same as the address
shown after MEMORY FREE AFTER:&.... IF THIS IS NOT THE CASE THE PROGRAM MUST
BE FREELY RELOCATABLE IF IT SHOULD WORK ! (see also Hints 'n help, 'real' ROMs)
 
If the program to be implemented is no BASIC program and no 'real' ROM program
the ROM generator asks for the executionaddress and the startaddress. The 
startaddress is the address to which the program will be copied after it's
RSX command has been entered. The entryaddress is the address to which the
CPC jumps in order to start the program. Normally you can choose the
suggested addresses (the original addresses).

NOTE: If the original entryaddress is &0000 you MUST change it otherwise the
      CPC will reset !

The last input you have to cope with is the question whether the program
should autostart. You can change the autostart option later in the -R- SHOW RSX
option, too. There an autostart program will be marked with a "*".

After you have succesfully entered all the necessary data the program will
be implemented in the current ROM. During the implementation you might encounter
the following problems or messages:

1. No problems at all. No messages. The program fits into the current ROM
   and will be implemented.

2. The program is too long for one ROM, it will be split up into two ROMs.
   This works as follows: the first part of the program (in the first ROM part)
   will be saved or installed and the second part of the program remains in
   the memory as the new current ROM. This second ROM can now be changed (you
   might add other programs, for example), saved or installed. Before you
   save or install the ROM you should change the ROM name (for example ROM #2).
   The same goes for the promptmessage: change it (useful if you want to make
   clear which ROMs belong together) even leave it out completely.
 
3. The current ROM is almost filled up already and the program is very long
   -> try to delete other programs from the current room in order to free some
      bytes.

4. The program is relatively short but the current ROM is almost full already
   -> try to delete other programs from the current room in order to free some
      bytes or accept that the new program will be split up into two ROMs !

5. The program is longer than about 31KB and therefore too long to be processed
   with the ROM generator. You should try to crunch it in order to shorten it
   a bit (try the CHEESE CRUNCHER V2.2 by Antoine, great piece of code !!!).

6. The program should run IN the ROM but is longer than about 16KB
   -> unfortunately IMPOSSIBLE !

NOTE: For easy handling you should avoid splitting programs up. It is also
      not the best thing to do to put the first part of a program into a ROM
      which already contains the second part of another ROM.

IMPORTANT: If a program has been split up into two ROMs both ROMs have to be
           installed if the program should work ! By the way, the order of the
           ROMs (part ROMs) or their ROM numbers are not relevant.

ANOTHER NOTE: If a program is split up the second part in the second ROM
              automatically gets a dummy RSX command which cannot be
              executed by BASIC. You must not change such a dummy RSX into
              an autostart RSX !

You should take care of saving of installing your, now hopefully working,
ROM especially if you change from the ROM generator to the SOFTBRENNER since
some actions of the SOFTBRENNER delete the current ROM (the ROM buffer). These
actions are:

1. LOAD & INSTALL
2. GET ROM
3. SHOW RSX "FROM DISC"
4. SAVE ROM
5. XTRACT

If one of these actions put a ROM generated by the ROM generator into the
ROM buffer it will be considered as the new current ROM !


----------------------------------------------------------------------
                     New options of the SOFTBRENNER V1.22    
----------------------------------------------------------------------

Since SOFTBRENNER v1.15 you have a new option (and a new RSX command):

-P- PARK ROMs.

Using this option you can switch off a background ROM (first byte &01)
WITHOUT a) switching off the 'RAM ROM socket'
        b) using the !ROMOFF command
        c) deleting the ROM

Parked ROMs will not initialised anymore and therefore are NOT active.
Using the same option again you can 'unpark' the ROM again. The park option
changes the first byte of a background ROM from &01 into &FE. You can 
have the same effect by using the editor but the park option is even easier.

Another new option in the main menu is the -F- COLOUR SELECTION. If you don't
like the white background just press the F key.


Since SOFTBRENNER v1.18 you have the new option -X- XTRACT.

This new feature makes it now possible to extract and save programs from
ROMs. For technical reasons this works only with ROMs generated with
the ROM generator  v1.11-1.22. The first version v1.02 is not supported
since those ROMs could contain only one program anyway !
The new possibility is quite handy for utility compilations (if you want
to 'recycle' old programs in new ROMs). Just extract the desired programs
from the old ROMs using the XTRACT option and save them. After that you can
generate a new ROM using the 'old' programs.

NOTE: 'Real' programs can cause problems since these are normally compiled
      for an exact address in the ROM (this is not the case for freely
      relocatable programs which are, saddly enough, only very few). If you
      have extracted a 'real' ROM program you can normally not be sure that
      it can be stored at it's original address (therefore it wouldn't work). 
      So, be careful !

----------------------------------------------------------------------
                          Hints 'n help
----------------------------------------------------------------------

Upgraded ROM-RAM-BOX 256KB - 16 RAM ROMs


Normally hardware upgrades (at least if the device to be upgraded was not
designed for an upgrade) cause problems. Fortunately the only problem
with the ROM-RAM-BOX upgrade is that now two ROMs have to share one switch
-> switch (4).
If you use one of the 8 DIP switches now always two ROMs are switched on or
off: ROM n and ROM n+8 (the ROMs which are displayed next to each other in
the SOFTBRENNER option -Z- SHOW ROMs).

Examples:
You switch off 'RAM ROM socket' 0 -> 'RAM ROM socket' 0 and 8 are off
  "   "     "        "          1 ->      "           1 and 9 are off
  "   "    on        "          8 ->      "           8 and 15 are on

and so on...


If you want to switch off explicitly one of those two ROMs without switching
off the other as well you can do that by using the !ROMOFF command of the
SOFTBRENNERs.
Example:
You want to use all ROMs exept for 3 and 5 and 6:
!ROMOFF,3,5,6  -> ROM 3,5 and 6 will be switched off (only by software).

In case you want to initialise ALL ROMs again you could type !ROMOFF,240
(240 is just a 'dummy ROM') -> all ROMs exept for 240 will be initalised.

If a program (for example DISC'O'MAGIC) reinitialises all ROMs after being
started (and even that ROM which you don't want to be) you could delete
the ROM using the -E- DELETE ROM or !KILL,no. 
But there is a better solution to the problem:
You can park the unwanted ROM using the -P- PARK ROM option or !ROMPARK,no.
After a reset the ROM is actually no more present. 'PARKED' will be displayed.
If you want to recover the ROM just use the park option again. You can only
park background ROM which are the most common ROMs.

You can park ROM manually, too: 'grab' the undesired ROM using the -G- GET
ROM option. Then change the first byte of the ROM (at &4000) into a &FE by
using the editor. To recover it again repeat the procedure and set the first
byte (at &4000) to its original value (a &01 for background ROMs).

It is a good idea to put ROMs that belong together 'next to each other'
(for example MAXAM  1.5  and  PROTEXT). You should do that also with two
part ROMs since then you switch on or off always both parts.
----------------------------------------------------------------------

'PARK' ROMs

See 'New options of SOFTBRENNERS V1.22' !

----------------------------------------------------------------------

'Real' ROMs

There are two main kinds of programs that can be implemented into the
current ROM: a) Programs that will be copied into the RAM or copied and 
                started after the RSX command was used
             b) Programmes that run IN the ROM. This kind of program makes the
                best use of the memory available in a ROM, because:
                1. less ROM for organisation purposes is used
                2. no RAM will be used

These programs have to fulfil certain criteria: they have to be able to run in
ROM (it must not contain selfmodifying code, etc.) and they must be able to
run at the address displayed in the ROM generator (MEMORY FREE AFTER:&....).
Example: in an empty current ROM the code of a 'real' ROM program can start
at &C2E2. Either your program is freely relocatable or the desired program
must be assembled for this startaddress (&C2E2). Of course this is only possible
if you have the sourcecode of the program. If this is not the case you have to
use the 'normal' way of implementing the program (copy into the RAM).
----------------------------------------------------------------------

CRUNCHER

If a program is longer than about 31KB or if you don't want a program to split
up into two ROMs you can try to crunch it.
We recommend the CHEESE  CRUNCHER  V2.2 by Antoine which is always good
for best results. As a good example for how useful crunching is, serves
best the wellknown DISC'O'MAGIC by Joker. Uncrunched about 16KB long it needs
to be split up into two ROMs. Crunched with the CHEESE CRUNCHER it is only
about 13KB long and can be put into ONE ROM together with other programs
without any problems. You see, before putting a program in a ROM you should
always try to crunch it.
----------------------------------------------------------------------

PROBLEMS WITH CRUNCHED PROGRAMS

Sometimes programs crunched with the CHEESE CRUNCHER do not work after being
put in a ROM. An explanation for this effect might be that the programs
get a very high startaddress after being crunched. Quite often this leads
to the effect that, while being copied and decrunched, the program overwrites
RAM areas that are reserved for the 'RSX system'.

Solution:
You could try to enter a lower startaddress (and also a lower entryaddress)
in the corresponding ROM generator menu. Sometimes you can also copy the
program into the screen memory (at &C000). This works, of course, only if
the crunched program is shorter than &4000 bytes and if the decrunch buffer
is not located at an address higher than &C000 !

Maybe you can change some of the crunching-parameters: try to alter the
buffer-address (&C000 and &C400 for example) !

                                                       
----------------------------------------------------------------------

MULTIPART PROGRAMS

Multipart programs can be implemented in a ROM quite easily, too:
often multipart programs consist of a small BASIC loader and the binary
main code. It is very common that the BASIC loader does nothing but loading
and starting the main code. In this case you can completely leave out the
BASIC loader.

Example:

10 MEMORY &7FFF
20 LOAD"MAIN",&8000
30 CALL &8000

In this case only the program "MAIN" is important.

The following example is slightly different:

10 MEMORY &7FFF
20 LOAD"SCREEN",&C000
30 LOAD"MAIN",&8000
40 CALL &8000

In this case, if you don't want to leave out the screen you must modify the
BASIC program a bit:

10 MEMORY &7FFF
20 !SCREEN
30 !MAIN

After the modification save the BASIC program again. In the ROM generator
you can now implement all parts of the program (-R- ADD RSX). The BASIC program
can be given a desired RSX name (for example RSX name 'GAME') the screen must
get the RSX 'SCREEN' and the main code must get the RSX 'MAIN'.
In the -R- ADD RSX option 'GAME' must be defined as 'copy into the RAM and
start', 'SCREEN' as 'only copy into the RAM' and 'MAIN' as 'copy into the RAM
and start'.

After a complete implementation you can start the program with !GAME.

This example shows an important detail which has to be taken into 
consideration: sometimes program parts are loaded to addresses that
are not their original startaddresses (LOAD"MAIN",&8000 instead of
LOAD"MAIN"->let's say the original startaddress is &4000). While implementing
those programs you must not choose the suggested address (here: &4000) but
choose the correct address (here: &8000). The same goes with the entryaddress:
the program might be saved with the entryaddress &4000 but it must be started
with CALL &8000 since it will be loaded to address &8000. So, you must choose
&8000 as the new entryaddress.

It is, of course, no disadvantage to crunch the screen as well as the main
code.
----------------------------------------------------------------------

AUTOSTART

Autostart is a very handy thing, although there are sometimes problems
with programs that reinitialise all ROMs when started (for example
DISC'O'MAGIC). In this case the autostart program would be started over
and over again. Therefore a tricky keyscan routine is implemented in ROM
generator ROMs: to prevent a program from being autostarted just press the
SPACE bar during the initialisation !

Problems can also occur if an autostarted program wants to use RSX commands
of ROMs that have not yet been initialised since the autostart program
interrupted the initialisation process. In such cases install the ROM with
the autostart programs on a ROM number as low as possible since the ROMs
are initialised downwards from 15 to 0 (7-0 at CPC 464).

Autostart is available since version 1.16 for BASIC programs, too.
----------------------------------------------------------------------

SAVING

Filename input in the SOFTBRENNER/ROM generator follows the same rules
as in BASIC. This means that you can also determine the drive and user
together with the filename.
Example:
Filename: 0B:TEST.ROM -> File "TEST.ROM" will be saved on drive b, user 0
Filename:  B:TEST.ROM -> File "TEST.ROM" will be saved on drive b, current user
----------------------------------------------------------------------

EDITOR

Besides quick patches you can do another handy thing using the editor:
you can switch ROMs off (without deleting them) by setting their first
byte (normally 0, 1, 2 or &80) to a value <> 0, 1, 2 or &80 (for example
&FE or &FF). After a reset this ROM will not be initialised anymore !
If you have chosen a &FE as the first byte 'PARKED' will be displayed
whilst 'EMPTY' is displayed if you chose a &FF. This 'park' method
can be done more easily using the -P- PARK ROMs option !

In addition you can change the name of a ROM or the promptmessage of a ROM
(useful with ROMs that have not been generated using the ROM generator).

Example: You want to suppress the promptmessage of a ROM.

You have to search the address in the ROM where the promptmessage is
stored. Then you have to look, which byte marks the end of the string
(the message). Frequently used bytes are &00 or &FF. You have to enter
this byte at the beginning of the promptmessage. If the promptmessage
reads for example "MUSIC ROM ACTIVE" you have to set the end mark instead
of the "M". After this procedure you have to install the ROM again and you
can test it. You can for example play around with some control codes such as
10 (&0A)->linefeed or 13(&0D)->carriage return which means that you insert
them before your new end mark (for example &0A,&0D,&00 -> lf,cr, END).
----------------------------------------------------------------------

'PLUS'-DOS-ROM-hint (for PLUS owners only)

We have patched the AMSDOS  v0.50 (the normal 6128 AMSDOS) so that you can
just put in in 'RAM ROM socket' 7 ! You can now have extemly easy 100%
disc compatibility to the 'old' generation. If you want the patch - just
contact us.
----------------------------------------------------------------------

'RAM-ROM' selection 8-15

Some words on putting ROMs in the 'RAM ROM sockets' 8-15:

Due to uncompatible programming some programs don't work if they are installed
above the DOS.

Example: The DOS has no. 7, a ROM is in 'RAM ROM socket' 14 installed. In the
worst case the program in ROM 14 is badly programmed and is doesn't work
correctly.

The reason:

Since the ROMs are initialised from no. 15 downwards to no. 1 and in this
case the DOS is not the first program to be initialised it does not get
the 'normal' workspace RAM (at &A700) but possibly &A200.

If the program on no. 14 needs the DOS workspace at &A700 it would not work !

Solution:
To make sure that the DOS is the first ROM to reserve its workspace
you should place it on the highest possible number (ideal is 15).

'Lower' DOS ROMs will be deleted or the built-in AMSDOS on number 7
will be overlayed with another ROM. After you have put the DOS on number
15 it would be extra-smart so 'grab' the built-in AMSDOS ROM, 'park' it 
and put it back on number 7. Although the AMSDOS on number 7 is not active, this
method ensures compatibility even with 'dumb' programs which directly jump
into ROM number 7.
----------------------------------------------------------------------

OLD VERSIONS

Since the ROM generator has been completely reprogrammed ROMs generated
with the SOFTBRENNER v1.02 can not be used in the new ROM generator.
ROMs generated with the newer versions v1.11-v1.15 are cross compatible.
Generally speaking you should always use the newest version of the ROM
generator. Since version 1.16 it is possible to autostart BASIC programs. This
new feature needs a lot more complex routines in the ROM header. This is
the reason why ROM generated with versions after v1.16 are no longer 
compatible with the older versions (see also EXTRACT PROGRAMS (XTRACT).
----------------------------------------------------------------------

EXTRACT PROGRAMS (XTRACT)

If you want to integrate routines from older ROM generator ROMs into new
ROMs you can simply extract the desired routines by using the new XTRACT
option of the SOFTBRENNER. Just extract the routines you want, save them
and generate new compilations.
-----------------------------------------------------------------------

CHECKSUM

Before a ROM is installed it will be tested whether it contains a standard
checksum routine. If this is the case the SOFTBRENNER checks whether the
checksum is correct. If not, the SOFTBRENNER corrects the checksum and
displays a message. Normally this happens with edited ROMs or with ROMs
generated with the ROM generator.

Attention: a checksum message can also be an indicator for a defect ROM
(maybe a defect ROM has been 'grabbed' and saved). In case of an uncontrolled
alternation of the ROM the checksum is wrong and during the initialisation
of the ROM a 'Checksum error' is displayed. The SOFTBRENNER always corrects
the checksum even if the ROM is defect ! Therefore the user has to decide
whether the message 'Checksum will be corrected' is an indicator for a defect
ROM or an edited or new generated ROM !
-----------------------------------------------------------------------

SOFTBRENNER ROM V1.22

The following RSX commands are implemented:
!SB               - starts the SOFTBRENNER
!INSTALL,(0-15)   - installs a ROM (data at &4000) on 'RAM ROM' 0-15
!KILLROM,(0-15)   - kills a ROM on 'RAM ROM' 0-15
!HELP             - lists the ROMs 0-15
!HELP,no          - lists RSX commands of ROM number
!ROMHELP          - same as HELP
!ROMOFF,no,no...  - initialises ALL ROMs (1-15) exept for those chosen by
                    number.
                    Example: ROM 1,3 and 15 are not wanted.
                    SO: !ROMOFF,1,3,15
                    Attention: Some ROM programs initialise all ROMs 
                               after being started and therefore switch
                               the ROMs disabled using the !ROMOFF command
                               again (for example: DISC'O'MAGIC)
!ROMPARK,no       - (UN)park a ROM on 'RAM ROM' number
----------------------------------------------------------------------

UTILITY ROM V1.16 (a small compilation of utilities)

!HELP            - lists the ROMs 0-15
!HELP,no         - lists the RSX commands of ROM number
!75HZ            - switches to 75HZ frame rate
!60HZ            - switches to 60HZ frame rate
!50HZ            - switches to 50HZ frame rate
!CRTC.RESET      - resets the CRTC
!GCAT            - CAT & information about entries on other USERs 
!GCAT,no         - same as above but also switches to USER no
!RAMCHECK        - information about attached RAM
!R               - 'saves' the memory into the E-RAM (block 0-2) 
!U               - 'recalls' the memory from the E-RAM
!PRE             - sets colours, SPEED KEY, key definitions
!KA              - CAT from drive A without switching to drive A
!KB              - CAT from drive B without switching to drive B
!KC              - CAT from drive C without switching to drive C
!INSTALL,no      - installs a ROM (data at &4000) on 'RAM ROM' number

Very useful for programmers are the commands !R and !U (newest version):
before you start a program which might cause the CPC to hang up 'save' the
memory (all settings and programs) in the E-RAM and then test your program.
If the CPC hangs up, just reset the computer and 'recall' the memory using the
!U command. If an ASIC window is open it will be closed before the memory is
saved.

All of tools are 'real' ROMs. That means that they don't use any RAM except for
their workspace !
----------------------------------------------------------------------

INSTALL.ASM

On the disc there is a fully documented assembler listing (MAXAM) which 
demonstrates how you transfer a ROM into the ROM-RAM-BOX. The difference
to the older listing is that the ROM to be installed (at &4000) will not
be erased anymore.
----------------------------------------------------------------------